Skip to main content

IBM Watson

This guide outlines the steps required to configure the IBM Watson Speech to Text service for use with the application's voicemail transcription service.

Watson uses an API Key and a unique Service URL for authentication, which are generated when you create a service instance in the IBM Cloud.

Prerequisites​

  • An IBM Cloud account. You can create a free account that includes a "Lite" plan for many services.

Step 1: Create a Watson Speech to Text Service​

First, you must create an instance of the Speech to Text service in your IBM Cloud account. This will provision your dedicated credentials.

  1. Log in to the IBM Cloud Dashboard: Navigate to https://cloud.ibm.com/.

  2. Navigate to the Catalog:

    • In the top search bar, type "Speech to Text" and select it from the results.
    • This will take you to the service creation page.

  3. Configure the Service: Fill out the creation form:

    • Location: Select a location where the service will be hosted (e.g., Dallas).
    • Pricing Plan: Select a plan. The Lite plan is free and is an excellent option for getting started and for low-volume usage.
    • Service Name: Give your service instance a unique name (e.g., fspbx-speech-to-text).
    • Review the terms and click Create.

  4. Wait for Provisioning: IBM Cloud will take a moment to provision the service instance. You will be redirected to the service's main page when it's ready.

Step 2: Retrieve API Key and Service URL​

After the service instance is created, you can access the credentials needed for the application.

  1. Navigate to the Speech to Text service instance you just created.
  2. In the left-hand menu, click on Manage.
  3. Copy the Credentials: On this page, you will see your credentials listed:
    • API Key: Copy this value.
    • URL: Copy this value. This is your unique service endpoint.

Security Warning: The API Key grants access to your IBM Watson service. Keep it secure and do not commit it to public version control.

Step 3: Configuration​

We will now configure the application to use the Watson credentials.

1. Update Environment Variables (.env)​

Add the following section to your .env file and populate it with the key and URL you copied from the IBM Cloud dashboard.

# --- IBM WATSON SPEECH-TO-TEXT CREDENTIALS ---
WATSON_SPEECH_API_KEY="paste_your_api_key_here"
WATSON_SPEECH_URL="paste_your_url_here"

2. Clear Configuration Cache​

To ensure the application loads the new environment variables, run the following commands:

cd /var/www/fspbx
php artisan config:cache
php artisan queue:restart

Step 4: Activate the Watson Transcription Provider​

Once the credentials are in place, the final step is to instruct the application to use Watson for new voicemail transcriptions.

  1. In the FS PBX user interface, navigate to the Default Settings section and then select Voicemail.
  2. Locate the setting named voicemail_queue_strategy. Update its value to modern.
  3. Locate the setting named transcribe_provider. Update its value to watson.
  4. Save the changes.

All new voicemails will now be sent to IBM Watson Speech to Text for transcription.

Troubleshooting​

Checking the Logs​

The first place to check for any transcription issues is the main FS PBX log file.

The log is located at: /var/www/fspbx/storage/logs/laravel.log

To watch the log file for new errors in real-time, open a terminal on your PBX server and run the following command. Leave this command running while you trigger a new voicemail transcription. Any errors generated by the process will appear in your terminal instantly.

tail -f /var/www/fspbx/storage/logs/laravel.log

Error: 401 Unauthorized​

This is the most common error and indicates an authentication problem.

  • Cause: The WATSON_SPEECH_API_KEY in your .env file is incorrect or has a typo. The service URL must also be correct for authentication to succeed. Verify both values carefully.

Error: 404 Not Found​

This error means the service endpoint could not be found.

  • Cause: The WATSON_SPEECH_URL in your .env file is incorrect. Ensure you have copied the entire URL exactly as it appears in the IBM Cloud credentials page.

Error: 403 Forbidden or Quota Exceeded Messages​

This indicates you are authenticated but not authorized to make the request, often due to usage limits.

  • Cause: If you are using the Lite plan, you may have exceeded the monthly limit for transcription minutes. Check your usage by navigating to Manage > Plan within your service instance in the IBM Cloud dashboard.